home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kio / netaccess.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-01-19  |  21.5 KB  |  541 lines
  1. /*
  2.     This file is part of the KDE libraries
  3.     Copyright (C) 1997 Torben Weis (weis@kde.org)
  4.     Copyright (C) 1998 Matthias Ettrich (ettrich@kde.org)
  5.     Copyright (C) 1999-2004 David Faure (faure@kde.org)
  6.  
  7.     This library is free software; you can redistribute it and/or
  8.     modify it under the terms of the GNU Library General Public
  9.     License as published by the Free Software Foundation; either
  10.     version 2 of the License, or (at your option) any later version.
  11.  
  12.     This library is distributed in the hope that it will be useful,
  13.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15.     Library General Public License for more details.
  16.  
  17.     You should have received a copy of the GNU Library General Public License
  18.     along with this library; see the file COPYING.LIB.  If not, write to
  19.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20.     Boston, MA 02110-1301, USA.
  21. */
  22.  
  23. #ifndef __kio_netaccess_h
  24. #define __kio_netaccess_h
  25.  
  26. #include <qobject.h>
  27. #include <qstring.h>
  28. #include <kio/global.h>
  29.  
  30. class QStringList;
  31. class QWidget;
  32. class KURL;
  33. template<typename T, typename K> class QMap;
  34.  
  35. namespace KIO {
  36.  
  37.   class Job;
  38.  
  39.   /**
  40.    * Net Transparency.
  41.    *
  42.    * NetAccess allows you to do simple file operation (load, save,
  43.    * copy, delete...) without working with KIO::Job directly.
  44.    * Whereas a KIO::Job is asynchronous, meaning that the
  45.    * developer has to connect slots for it, KIO::NetAccess provides
  46.    * synchronous downloads and uploads, as well as temporary file
  47.    * creation and removal. The functions appear to be blocking,
  48.    * but the Qt event loop continues running while the operations
  49.    * are handled. This means that the GUI will not freeze.
  50.    *
  51.    * This class isn't meant to be used as a class but only as a simple
  52.    * namespace for static functions, though an instance of the class
  53.    * is built for internal purposes.
  54.    *
  55.    * Port to kio done by David Faure, faure@kde.org
  56.    *
  57.    * @short Provides an easy, synchronous interface to KIO file operations.
  58.    */
  59. class KIO_EXPORT NetAccess : public QObject
  60. {
  61.   Q_OBJECT
  62.  
  63. public:
  64.     /**
  65.      * Downloads a file from an arbitrary URL (@p src) to a
  66.      * temporary file on the local filesystem (@p target).
  67.      *
  68.      * If the argument
  69.      * for @p target is an empty string, download will generate a
  70.      * unique temporary filename in /tmp. Since @p target is a reference
  71.      * to QString you can access this filename easily. Download will
  72.      * return true if the download was successful, otherwise false.
  73.      *
  74.      * Special case:
  75.      * If the URL is of kind file:, then no downloading is
  76.      * processed but the full filename is returned in @p target.
  77.      * That means you @em have to take care about the @p target argument.
  78.      * (This is very easy to do, please see the example below.)
  79.      *
  80.      * Download is synchronous. That means you can use it like
  81.      * this, (assuming @p u is a string which represents a URL and your
  82.      * application has a loadFile() function):
  83.      *
  84.      * \code
  85.      * QString tmpFile;
  86.      * if( KIO::NetAccess::download( u, tmpFile, window ) )
  87.      * {
  88.      *   loadFile( tmpFile );
  89.      *   KIO::NetAccess::removeTempFile( tmpFile );
  90.      * } else {
  91.      *   KMessageBox::error(this, KIO::NetAccess::lastErrorString() );
  92.      * }
  93.      * \endcode
  94.      *
  95.      * Of course, your user interface will still process exposure/repaint
  96.      * events during the download.
  97.      *
  98.      * If the download fails, lastError() and lastErrorString() will be set.
  99.      *
  100.      * @param src URL Reference to the file to download.
  101.      * @param target String containing the final local location of the
  102.      *               file.  If you insert an empty string, it will
  103.      *               return a location in a temporary spot. <B>Note:</B>
  104.      *               you are responsible for the removal of this file when
  105.      *               you are finished reading it using removeTempFile.
  106.      * @param window main window associated with this job. This is used to
  107.      *               automatically cache and discard authentication information
  108.      *               as needed. If NULL, authentication information will be
  109.      *               cached only for a short duration after which the user will
  110.      *               again be prompted for passwords as needed.
  111.      * @return true if successful, false for failure.  Use lastErrorString() to
  112.      *         get the reason it failed.
  113.      *
  114.      * @see lastErrorString()
  115.      * @since 3.2
  116.      */
  117.     static bool download(const KURL& src, QString & target, QWidget* window);
  118.  
  119.     /**
  120.      * @deprecated. Use the function above instead.
  121.      */
  122.     static bool download(const KURL& src, QString & target) KDE_DEPRECATED;
  123.  
  124.     /**
  125.      * Removes the specified file if and only if it was created
  126.      * by KIO::NetAccess as a temporary file for a former download.
  127.      *
  128.      * Note: This means that if you created your temporary with KTempFile,
  129.      * use KTempFile::unlink() or KTempFile::setAutoDelete() to have
  130.      * it removed.
  131.      *
  132.      * @param name Path to temporary file to remove.  May not be
  133.      *             empty.
  134.      */
  135.     static void removeTempFile(const QString& name);
  136.  
  137.     /**
  138.      * Uploads file @p src to URL @p target.
  139.      *
  140.      * Both must be specified, unlike download.
  141.      * Note that this is assumed to be used for saving a file over
  142.      * the network, so overwriting is set to true. This is not the
  143.      * case with copy.
  144.      *
  145.      * @param src URL Referencing the file to upload.
  146.      * @param target URL containing the final location of the file.
  147.      * @param window main window associated with this job. This is used to
  148.      *               automatically cache and discard authentication information
  149.      *               as needed. If NULL, authentication information will be cached
  150.      *               only for a short duration after which the user will again be
  151.      *               prompted for passwords as needed.
  152.      *
  153.      * @return true if successful, false for failure
  154.      * @since 3.2
  155.      */
  156.     static bool upload(const QString& src, const KURL& target, QWidget* window);
  157.  
  158.     /**
  159.      * @deprecated. Use the function above instead.
  160.      */
  161.     static bool upload(const QString& src, const KURL& target) KDE_DEPRECATED;
  162.  
  163.     /**
  164.      * Alternative to upload for copying over the network.
  165.      * Overwrite is false, so this will fail if @p target exists.
  166.      *
  167.      * This one takes two URLs and is a direct equivalent
  168.      * of KIO::file_copy (not KIO::copy!).
  169.      * It will be renamed file_copy in KDE4, so better use file_copy.
  170.      *
  171.      * @param src URL Referencing the file to upload.
  172.      * @param target URL containing the final location of the file.
  173.      * @param window main window associated with this job. This is used to
  174.      *               automatically cache and discard authentication information
  175.      *               as needed. If NULL, authentication information will be cached
  176.      *               only for a short duration after which the user will again be
  177.      *               prompted for passwords as needed.
  178.      *
  179.      * @return true if successful, false for failure
  180.      */
  181.     static bool copy( const KURL& src, const KURL& target, QWidget* window );
  182.     // KDE4: rename to file_copy
  183.  
  184.     /**
  185.      * @deprecated. Use the function above instead.
  186.      */
  187.     static bool copy( const KURL& src, const KURL& target ) KDE_DEPRECATED;
  188.     // KDE4: merge with above
  189.  
  190.     /**
  191.      * Full-fledged equivalent of KIO::file_copy
  192.      */
  193.     static bool file_copy( const KURL& src, const KURL& dest, int permissions=-1,
  194.                             bool overwrite=false, bool resume=false, QWidget* window = 0L );
  195.  
  196.     /**
  197.      * Full-fledged equivalent of KIO::file_move.
  198.      * Moves or renames *one file*.
  199.      * @since 3.2
  200.      */
  201.     static bool file_move( const KURL& src, const KURL& target, int permissions=-1,
  202.                            bool overwrite=false, bool resume=false, QWidget* window = 0L );
  203.  
  204.  
  205.     /**
  206.      * Alternative method for copying over the network.
  207.      * Overwrite is false, so this will fail if @p target exists.
  208.      *
  209.      * This one takes two URLs and is a direct equivalent
  210.      * of KIO::copy!.
  211.      * This means that it can copy files and directories alike
  212.      * (it should have been named copy()).
  213.      *
  214.      * @param src URL Referencing the file to upload.
  215.      * @param target URL containing the final location of the
  216.      *               file.
  217.      * @param window main window associated with this job. This is used to
  218.      *               automatically cache and discard authentication information
  219.      *               as needed. If NULL, authentication information will be cached
  220.      *               only for a short duration after which the user will again be
  221.      *               prompted for passwords as needed.
  222.      * @return true if successful, false for failure
  223.      */
  224.     static bool dircopy( const KURL& src, const KURL& target, QWidget* window );
  225.  
  226.     /**
  227.      * @deprecated. Use the function above instead.
  228.      */
  229.     static bool dircopy( const KURL& src, const KURL& target ) KDE_DEPRECATED; // KDE4: merge
  230.  
  231.     /**
  232.      * Overloaded method, which takes a list of source URLs
  233.      */
  234.     static bool dircopy( const KURL::List& src, const KURL& target, QWidget* window = 0L );
  235.  
  236.     /**
  237.      * Full-fledged equivalent of KIO::move.
  238.      * Moves or renames one file or directory.
  239.      * @since 3.2
  240.      */
  241.     static bool move( const KURL& src, const KURL& target, QWidget* window = 0L );
  242.  
  243.     /**
  244.      * Full-fledged equivalent of KIO::move.
  245.      * Moves or renames a list of files or directories.
  246.      * @since 3.2
  247.      */
  248.     static bool move( const KURL::List& src, const KURL& target, QWidget* window = 0L );
  249.  
  250.     /**
  251.      * Tests whether a URL exists.
  252.      *
  253.      * @param url the URL we are testing
  254.      * @param source if true, we want to read from that URL.
  255.      *               If false, we want to write to it.
  256.      * IMPORTANT: see documentation for KIO::stat for more details about this.
  257.      * @param window main window associated with this job. This is used to
  258.      *               automatically cache and discard authentication information
  259.      *               as needed. If NULL, authentication information will be
  260.      *               cached only for a short duration after which the user will
  261.      *               again be prompted for passwords as needed.
  262.      * @return true if the URL exists and we can do the operation specified by
  263.      *              @p source, false otherwise
  264.      * @since 3.2
  265.      */
  266.     static bool exists(const KURL& url, bool source, QWidget* window);
  267.  
  268.     /**
  269.      * @deprecated. Use the function above instead.
  270.      * @since 3.2
  271.      */
  272.     static bool exists(const KURL& url, QWidget* window) KDE_DEPRECATED;
  273.  
  274.     /**
  275.      * @deprecated. Use the function above instead.
  276.      */
  277.     static bool exists(const KURL& url) KDE_DEPRECATED;
  278.  
  279.     /**
  280.      * @deprecated. Use the function above instead.
  281.      */
  282.     static bool exists(const KURL& url, bool source) KDE_DEPRECATED; // KDE4: merge
  283.  
  284.     /**
  285.      * Tests whether a URL exists and return information on it.
  286.      *
  287.      * This is a convenience function for KIO::stat
  288.      * (it saves creating a slot and testing for the job result).
  289.      *
  290.      * @param url The URL we are testing.
  291.      * @param entry The result of the stat. Iterate over the list
  292.      * of atoms to get hold of name, type, size, etc., or use KFileItem.
  293.      * @param window main window associated with this job. This is used to
  294.      *               automatically cache and discard authentication information
  295.      *               as needed. If NULL, authentication information will be
  296.      *               cached only for a short duration after which the user will
  297.      *               again be prompted for passwords as needed.
  298.      * @return true if successful, false for failure
  299.      */
  300.     static bool stat(const KURL& url, KIO::UDSEntry & entry, QWidget* window);
  301.  
  302.     /**
  303.      * @deprecated. Use the function above instead.
  304.      */
  305.     static bool stat(const KURL& url, KIO::UDSEntry & entry) KDE_DEPRECATED;
  306.  
  307.     /**
  308.      * Tries to map a local URL for the given URL.
  309.      *
  310.      * This is a convenience function for KIO::stat + parsing the
  311.      * resulting UDSEntry.
  312.      *
  313.      * @param url The URL we are testing.
  314.      * @param window main window associated with this job. This is used to
  315.      *               automatically cache and discard authentication information
  316.      *               as needed. If NULL, authentication information will be
  317.      *               cached only for a short duration after which the user will
  318.      *               again be prompted for passwords as needed.
  319.      * @return a local URL corresponding to the same ressource than the
  320.      *         original URL, or the original URL if no local URL can be mapped
  321.      * @since 3.5
  322.      */
  323.     static KURL mostLocalURL(const KURL& url, QWidget* window);
  324.  
  325.     /**
  326.      * Deletes a file or a directory in a synchronous way.
  327.      *
  328.      * This is a convenience function for KIO::del
  329.      * (it saves creating a slot and testing for the job result).
  330.      *
  331.      * @param url The file or directory to delete.
  332.      * @param window main window associated with this job. This is used to
  333.      *               automatically cache and discard authentication information
  334.      *               as needed. If NULL, authentication information will be
  335.      *               cached only for a short duration after which the user will
  336.      *               again be prompted for passwords as needed.
  337.      * @return true on success, false on failure.
  338.      */
  339.     static bool del( const KURL & url, QWidget* window );
  340.  
  341.     /**
  342.      * @deprecated. Use the function above instead. Passing NULL as the
  343.      *             additional argument will give the same behaviour, but
  344.      *             you should try to identify a suitable parent widget
  345.      *             if at all possible.
  346.      */
  347.     static bool del( const KURL & url ) KDE_DEPRECATED;
  348.  
  349.     /**
  350.      * Creates a directory in a synchronous way.
  351.      *
  352.      * This is a convenience function for @p KIO::mkdir
  353.      * (it saves creating a slot and testing for the job result).
  354.      *
  355.      * @param url The directory to create.
  356.      * @param window main window associated with this job. This is used to
  357.      *               automatically cache and discard authentication information
  358.      *               as needed. If NULL, authentication information will be
  359.      *               cached only for a short duration after which the user will
  360.      *               again be prompted for passwords as needed.
  361.      * @param permissions directory permissions.
  362.      * @return true on success, false on failure.
  363.      */
  364.     static bool mkdir( const KURL & url, QWidget* window, int permissions = -1 );
  365.  
  366.     /**
  367.      * @deprecated. Use the function above instead. Passing NULL as the
  368.      *             additional argument will give the same behaviour, but
  369.      *             you should try to identify a suitable parent widget
  370.      *             if at all possible.
  371.      */
  372.     static bool mkdir( const KURL & url, int permissions = -1 ) KDE_DEPRECATED;
  373.  
  374.     /**
  375.      * Executes a remote process via the fish ioslave in a synchronous way.
  376.      *
  377.      * @param url The remote machine where the command should be executed.
  378.      *            e.g. fish://someuser\@somehost:sshport/
  379.      *            some special cases exist.
  380.      *            fish://someuser\@localhost/
  381.      *            will use su instead of ssh to connect and execute the command.
  382.      *            fish://someuser\@localhost:port/
  383.      *            will use ssh to connect and execute the command.
  384.      * @param command The command to be executed.
  385.      * @param window main window associated with this job. This is used to
  386.      *               automatically cache and discard authentication information
  387.      *               as needed. If NULL, authentication information will be
  388.      *               cached only for a short duration after which the user will
  389.      *               again be prompted for passwords as needed.
  390.      * @return The resulting output of the @p command that is executed.
  391.      */
  392.     static QString fish_execute( const KURL & url, const QString command, QWidget* window );
  393.  
  394.     /**
  395.      * This function executes a job in a synchronous way.
  396.      * If a job fetches some data, pass a QByteArray pointer as data parameter to this function
  397.      * and after the function returns it will contain all the data fetched by this job.
  398.      *
  399.      * <code>
  400.      * KIO::Job *job = KIO::get( url, false, false );
  401.      * QMap<QString, QString> metaData;
  402.      * metaData.insert( "PropagateHttpHeader", "true" );
  403.      * if ( NetAccess::synchronousRun( job, 0, &data, &url, &metaData ) ) {
  404.      *   QString responseHeaders = metaData[ "HTTP-Headers" ];
  405.      *   kdDebug()<<"Response header = "<< responseHeaders << endl;
  406.      * }
  407.      * </code>
  408.      *
  409.      * @param job job which the function will run. Note that after this function
  410.      *            finishes running, job is deleted and you can't access it anymore!
  411.      * @param window main window associated with this job. This is used to
  412.      *               automatically cache and discard authentication information
  413.      *               as needed. If NULL, authentication information will be
  414.      *               cached only for a short duration after which the user will
  415.      *               again be prompted for passwords as needed.
  416.      * @param data if passed and relevant to this job then it will contain the data
  417.      *               that was fetched by the job
  418.      * @param finalURL if passed will contain the final url of this job (it might differ
  419.      *                 from the one it was created with if there was a redirection)
  420.      * @param metaData you can pass a pointer to the map with meta data you wish to
  421.      *                 set on the job. After the job finishes this map will hold all the
  422.      *                 meta data from the job.
  423.      *
  424.      * @return true on success, false on failure.
  425.      *
  426.      * @since 3.4
  427.      */
  428.     static bool synchronousRun( Job* job, QWidget* window, QByteArray* data=0,
  429.                                 KURL* finalURL=0, QMap<QString,QString>* metaData=0 );
  430.  
  431.     /**
  432.      * @internal
  433.      * This function is not implemented!?
  434.      * (only mimetypeInternal)
  435.      *
  436.      * Determines the mimetype of a given URL.
  437.      *
  438.      * This is a convenience function for KIO::mimetype.  You
  439.      * should call this only when really necessary.
  440.      * KMimeType::findByURL can determine extension a lot faster, but
  441.      * less reliably for remote files. Only when findByURL() returns
  442.      * unknown (application/octet-stream) then this one should be
  443.      * used.
  444.      *
  445.      * @param url The URL whose mimetype we are interested in.
  446.      * @param window main window associated with this job. This is used to
  447.      *               automatically cache and discard authentication information
  448.      *               as needed. If NULL, authentication information will be
  449.      *               cached only for a short duration after which the user will
  450.      *               again be prompted for passwords as needed.
  451.      * @return The mimetype name.
  452.      */
  453.     static QString mimetype( const KURL & url, QWidget* window );
  454.  
  455.     /**
  456.      * @deprecated. Use the function above instead. Passing NULL as the
  457.      *             additional argument will give the same behaviour, but
  458.      *             you should try to identify a suitable parent widget
  459.      *             if at all possible.
  460.      */
  461.     static QString mimetype( const KURL & url ) KDE_DEPRECATED;
  462.  
  463.     /**
  464.      * Returns the error string for the last job, in case it failed.
  465.      * Note that this is already translated.
  466.      * @return the last error string, or QString::null
  467.      */
  468.     static QString lastErrorString() { return lastErrorMsg ? *lastErrorMsg : QString::null; }
  469.  
  470.     /**
  471.      * Returns the error code for the last job, in case it failed.
  472.      * @return the last error code
  473.      * @since 3.3
  474.      */
  475.     static int lastError() { return lastErrorCode; }
  476.  
  477. private:
  478.     /**
  479.      * Private constructor
  480.      */
  481.     NetAccess() : m_metaData(0), d(0) {}
  482.  
  483.     /**
  484.      * Private destructor
  485.      */
  486.     ~NetAccess() {}
  487.  
  488.     /**
  489.      * Internal methods
  490.      */
  491.     bool filecopyInternal(const KURL& src, const KURL& target, int permissions,
  492.                           bool overwrite, bool resume, QWidget* window, bool move);
  493.     bool dircopyInternal(const KURL::List& src, const KURL& target,
  494.                          QWidget* window, bool move);
  495.     bool statInternal(const KURL & url, int details, bool source, QWidget* window = 0);
  496.  
  497.     bool delInternal(const KURL & url, QWidget* window = 0);
  498.     bool mkdirInternal(const KURL & url, int permissions, QWidget* window = 0);
  499.     QString fish_executeInternal(const KURL & url, const QString command, QWidget* window = 0);
  500.     bool synchronousRunInternal( Job* job, QWidget* window, QByteArray* data,
  501.                                  KURL* finalURL, QMap<QString,QString>* metaData );
  502.  
  503.     QString mimetypeInternal(const KURL & url, QWidget* window = 0);
  504.     void enter_loop();
  505.  
  506.     /**
  507.      * List of temporary files
  508.      */
  509.     static QStringList* tmpfiles;
  510.  
  511.     static QString* lastErrorMsg;
  512.     static int lastErrorCode;
  513.  
  514.     friend class I_like_this_class;
  515.  
  516. private slots:
  517.     void slotResult( KIO::Job * job );
  518.     void slotMimetype( KIO::Job * job, const QString & type );
  519.     void slotData( KIO::Job*, const QByteArray& );
  520.     void slotRedirection( KIO::Job*, const KURL& );
  521.  
  522. private:
  523.     UDSEntry m_entry;
  524.     QString m_mimetype;
  525.     QByteArray m_data;
  526.     KURL m_url;
  527.     QMap<QString, QString> *m_metaData;
  528.  
  529.     /**
  530.      * Whether the download succeeded or not
  531.      */
  532.     bool bJobOK;
  533.  
  534. private:
  535.     class NetAccessPrivate* d; // not really needed, the ctor is private already.
  536. };
  537.  
  538. }
  539.  
  540. #endif
  541.